The goal is that every dependency carrying its own SIMD instead consumes
ndarray::simd -- all SIMD living once, audited, in one place. This records
the rungs, what is proven at each, and the order.

The load-bearing finding is the cycle map, and it is measured rather than
inferred: whether a dependency CAN consume ndarray::simd is decided by which
PACKAGE in the workspace pulls it, not by the workspace as a whole.

  chacha20          crates/encryption -> ... -> chacha20        no cycle
  curve25519-dalek  crates/encryption -> ed25519-dalek -> ...   no cycle
  blake3            ROOT ndarray (std feature, 11 hpc files)    CYCLE

  $ cargo tree -p ndarray -i curve25519-dalek
  error: package ID specification `curve25519-dalek` did not match any packages

Only blake3 is pulled by the root package, so only blake3 closes a loop. The
intuitive rule -- "ndarray depends on X, so X cannot depend on ndarray" -- is
wrong at workspace granularity and would have parked two rungs that have no
blocker at all.

Second scoping finding: ndarray's own blake3 usage is entirely single-input
(hash / Hasher::{new,new_keyed,update,finalize,finalize_xof}). No hash_many.
So cutting the cycle needs only the PORTABLE core -- scalar [u32;16] compress
plus the chunk/tree/XOF state machine -- which uses no SIMD at all. That
splits the rung into 3a (cut the cycle, no benchmark needed to justify it)
and 3b (hash_many throughput on the merged shuffle surface, which is where a
benchmark matters and which is not on the critical path).

Rungs 1 and 2 are merged and measured: the U32x16 ARX triple at the AVX2
instruction floor, and the shuffle surface parity-checked against the real
intrinsics on all six backends. Rungs 4-6 (chacha20, dalek, the u64 ARX lane
for BLAKE2b/argon2) are independent of each other and of 3a.

Stated plainly in the doc: nothing here is claimed to be faster. Every rung
is measured at instruction class, never at time, and no benchmark of any rung
against its upstream equivalent has been run. Rung 5 is also explicitly not a
defect -- `serial` is a correct, deliberate choice and the dalek vector
backend serves no operation this crate performs.

EPIPHANIES entry records the per-package cycle rule and that its failure mode
is SILENT: cargo does not error, it declines the patch and falls back to the
registry crate with [[patch.unused]], so a port done anyway compiles clean
and does nothing -- the same shape as the chacha20 patch, now two independent
instances in one dependency graph.

Rung 3a of the ladder, landed as the module + the measurement, WITHOUT the
call-site swap -- because the swap turns out to have a price tag.

## The module

src/hpc/blake3.rs, 771 lines, transcribed from upstream's own
reference_impl/reference_impl.rs (the spec-referenced serial implementation).
No unsafe, no core::arch, no new dependencies. Scoped by the finding that
ndarray's blake3 usage is entirely single-input -- 14 call sites across 8
files use only hash / Hasher::{new,new_keyed,update,finalize,finalize_xof} /
Hash::as_bytes, no hash_many -- so the serial core suffices.

Correctness proven against the official vectors, vendored alongside: 35/35
cases, unkeyed AND keyed, each at both 32-byte length and full extended
length via finalize_xof().fill() -- 140 assertions, input lengths 0..102400.
Plus streaming (one update vs many 37-byte updates over 102400 bytes), empty
input, and incremental fill.

Hash::eq is CONSTANT-TIME. The transcription arrived with a plain `==`, which
leaks match-prefix length through timing when a BLAKE3 output is used as a
MAC; upstream uses the constant_time_eq crate, and since this takes no new
deps the XOR-fold is written inline with a black_box on the accumulator. No
call site compares two Hash values today (seal.rs compares the truncated
MerkleRoot), so it is a guard for future consumers rather than a live fix.

## The measurement, and why the swap is not in this commit

First actual TIME number in this arc -- everything prior was
instruction-class. `.claude/knowledge/blake3-ab-bench/`, release, two runs:

  16 B     137 ns vs 100 ns   1.34x
  256 B    445 ns vs 350 ns   1.28x
  2 KB     4.3 us vs 2.7 us   1.34-1.60x
  64 KB    115 us vs  23 us   4.6-5.1x

Two gaps, different causes. The 64 KB gap is the absent hash_many (rung 3b).
The 1.3x small-input gap is NOT -- at 16 B there is one compression and no
parallelism to be had; the crate is faster because it SIMD-accelerates the
single compress itself. Closing that needs a U32x4-shaped compress, a rung
the plan did not have. Call it 3c.

So the earlier framing -- "removes things, needs no benchmark to justify" --
was true about what it removes and silent about what it costs. Dropping the
dependency is a trade, and it is the operator's call, so the call sites still
use the external crate here.

## Four corrections from codex on #268, all valid

- "No CI job compiles the chacha20 ndarray_simd backend" is FALSE.
  ci.yaml:141-142 builds vendor/chacha20 for wasm32+simd128, selecting that
  backend, under a comment calling it the wasm matryoshka guard. Only the
  AVX-512 arm is uncovered. Fixed here AND in the already-merged
  chacha20-vendoring-blast-radius.md. Fourth instance of the same
  scope-quantifier error: checked the x86 path, generalized to all targets.
- 3a does NOT remove a C build. features = ["pure"] removed all C/ASM in
  #264 already. 3a removes the Rust dependency and its intrinsic surface.
  Overstating this matters when the counterweight is transcribing a crypto
  implementation.
- The ordering arrows from 3a to rungs 4-6 contradicted the same section's
  own next sentence and would serialize independent work. Only 3a -> 3b is
  real; chacha20's backend already depends on ndarray, dalek has no cycle,
  and the u64 lane lives inside ndarray.
- [[patch.unused]] is NOT cargo's cycle diagnostic. Cargo reports the cycle
  by naming the chain (cargo update -p blake3 did); an unused patch only
  means the patch was not selected, usually a version mismatch or a stale
  lockfile. Conflating them teaches misdiagnosis and undermines the
  cargo-tree check the entry prescribes.

4 blake3 tests pass; clippy clean; fmt clean.

…pill

Operator question: what about the synergies of making 4096 bit / 512 byte
the default lane, since that is the canonical SoA node size anyway
(key(16) | edges(16) | value(480))?

Answered by measurement rather than argument. U32x16 is 512 BIT -- one eighth
of a node -- so a node-wide unit is [U32x16; 8] = 128 u32 lanes. It cannot be
a register type (512 byte is 8 zmm / 16 ymm), so it is necessarily a TILE over
the existing lane, exactly as U32x16 is already a polyfill over 2 ymm on avx2.
The open question was whether the wider unit costs anything, and the failure
mode to watch was spill -- 128 u32 against 16 architectural registers.

Two probes, same work, asserted bit-for-bit identical in the driver:

  arx_node4096     98 packed / 0 scalar / 0 memory
  arx_lane512_x8   81 packed / 0 scalar / 0 memory

The ARITHMETIC IS IDENTICAL: 16 vpaddd + 16 vpxor + 16 vpshufb + 33 vmovdqa in
both. The 17-instruction delta is 16 vmovaps + 1 vxorps -- the dead zero-init
of [U32x16::splat(0); 8] in the loop form, which an implementation building
the array by value does not emit. Neither form spills.

So the node width is free, and the discriminating property is LIVENESS rather
than width:

  streaming / elementwise (ARX, bitwise, add-mul)  each vector independent,
                                                   never all live -> 0 spill
  whole-node-live (a transpose)                    all live at once ->
                                                   transpose_16x16_composed
                                                   pays 41 memory ops

That is the rule to design a node-wide default unit against: viable for
streaming work; the ops that must stay lane-width are the ones needing the
whole node resident.

Also widens the blake3 A/B bench to the sizes this substrate actually hashes
-- 480 B (the node's value region) and 512 B (the node itself) sat in the gap
between the previous 256 and 2048 samples. At the canonical node size the
in-tree BLAKE3 is 1.28x (848 ns vs 664 ns), and the 4.8x bulk gap is
irrelevant there because 512 B never reaches hash_many. That reframes the
swap decision from a curve into a single number.

…n it

`ChunkState::update` does not split across chunks — `Hasher::update` caps
each call via `want = CHUNK_LEN - self.chunk_state.len()`. The `array_chunks`
fast path silently depends on that cap: `full = (input.len() - 1) / BLOCK_LEN`
is only bounded by the chunk if the caller already bounded the input. Given a
longer slice it would compress more than 16 blocks under one chunk counter and
produce a wrong-but-plausible hash.

The official test vectors would NOT catch that. They only reach this method
through `Hasher::update`, so they exercise the invariant rather than testing
it — the failure mode is a future refactor of the caller, or any direct call,
not a bad vector.

So assert it at the point of reliance instead of trusting a caller 250 lines
away. `debug_assert!` rather than `assert!`: this is an internal API whose
callers are all in this file, the release path should keep the fast path
branch-free, and the vectors already cover every boundary the fast path turns
on (63/64/65, 127/128/129, 1023/1024/1025).

Control-tested rather than assumed: a temporary test calling
`ChunkState::update` with `CHUNK_LEN + 1` bytes fires it —
"ChunkState::update overran a chunk: 0 + 1025 > 1024" — so the assert
discriminates. The temporary test is not kept; it would have to be
`#[should_panic]` on a debug-only assert, which is a fragile shape.

Found by reading the fast path adversarially while an external review was
pending, on the principle that the automated pass should land against an
independent check rather than be the only one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfbkUCBbtZhy3yjSfCDHp

…iming doc

Addresses the CodeRabbit pass on #268. Taking the findings that hold and
saying which do not, rather than applying all nine.

FIXED — correctness:

- **`derive_key` had zero vector coverage.** The parser read `input_len`,
  `hash`, and `keyed_hash` and skipped past the `derive_key` field already
  present in the file. It is the one public mode built as TWO passes
  (DERIVE_KEY_CONTEXT over the context string, whose output keys a
  DERIVE_KEY_MATERIAL pass over the material), so a swapped or collapsed
  transcription would have been invisible while hash/keyed_hash stayed green.
  Now asserted for all 35 cases at both the 32-byte and extended XOF lengths.
  It passed on the first run — the transcription was right; it just wasn't
  proven. Control-tested: swapping the two flags fails ONLY the new assertion.

- **`Hash::eq`'s documentation described the opposite of the code.** The
  doc-comment said `read_volatile` (the code uses `core::hint::black_box`) and
  the not-transcribed list flatly asserted "`PartialEq` here is a normal
  short-circuiting byte-array compare" — stale since the constant-time fold
  landed. On a MAC-comparison path a backwards timing claim is worse than no
  claim: an auditor would have believed this file leaks match-prefix length
  when it does not. Also now states that `black_box` is a best-effort barrier,
  not a guarantee; the data-independent loop is the actual property.

FIXED — hazards:

- `run.sh` copied the bench to a fixed `examples/blake3_ab.rs` and had the EXIT
  trap `rm` it unconditionally: a pre-existing file there would be clobbered
  and then deleted. Now refuses to overwrite, and only removes the directory it
  created.
- `shiftor_rot_u64x8` is `pub` and took arbitrary `u32` into `a >> n` — a debug
  panic and a release wrapping-shift for `n >= 64`. Normalized at the PUBLIC
  wrapper and deliberately NOT in the measured inner body, which would have
  changed the codegen the oracle exists to observe.
- Rotate test extended past 64 (65/127/128/191) against std's `u64::rotate_*`,
  pinning the mod-64 contract rather than only the width case.
- Test-local context const renamed `VECTORS_CONTEXT`; as `DERIVE_KEY_CONTEXT`
  it shadowed the module-scope u32 flag of that name.
- Redundant `.into()` in `derive_key` (`clippy::useless_conversion`).
- The `pub mod blake3` incident history was an OUTER doc comment, so rustdoc
  would publish it as module documentation. Now a plain `//` comment.

Three more stale doc claims, all the same class already corrected elsewhere in
this PR — an assertion outliving the change that falsified it:

- EPIPHANIES said "an error there means no cycle and the work is unblocked"
  one paragraph after explaining the error is ambiguous. Read literally it
  marks blocked work unblocked on the strength of a typo. Now a four-step
  procedure with the error explicitly inconclusive.
- crypto-lane-status prescribed an explicit shift-or for AVX2/NEON/wasm,
  contradicting the measurement directly above it (LLVM folds the two forms
  byte-identically) and misdescribing what shipped.
- blake3-in-tree-measured still credited the swap with removing the C build,
  already removed by `features = ["pure"]` in #264.

NOT taken, with reasons:

- Doctest examples on every public API. Worth doing, but it is a separate
  change across a surface this PR is not otherwise touching, and the vectors
  already smoke-test the public path harder than an example would.
- Caching the compressed block in `OutputReader`. A real inefficiency for
  small repeated `fill` calls, but unmeasured, and the module is explicitly
  not on a hot path pending the swap ruling.
- Deduplicating the rotate body across backends. Every other lane type in this
  crate is duplicated per backend by design; collapsing one method would make
  it the exception, not the rule.
- Secret-scanner allowlist for the vectors file. Correct that the hex is
  published test data, not credentials, but no scanner config lives in this
  repo to add it to.

Full lib suite green: 2200 passed, 0 failed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfbkUCBbtZhy3yjSfCDHp